[spin]: Rework trigger docs #1450

ThorstenHans · 2025-01-09T16:24:27Z

This PR is a rework of trigger related Spin documentation.

Once all triggers are documented, users will

be able to spot all different triggers
get instructions for installing them
see basic samples and fundamental app configuration

Sub Tasks

Merge once completed

Content must go through a pre-merge checklist.

Pre-Merge Content Checklist

This documentation has been checked to ensure that:

The title, template, and date are all set
Does this PR have a new menu item (anywhere in templates/*.hbs files) that points to a document .md that is set to publish in the future? If so please only publish the .md and .hbs changes in real-time (otherwise there will be a menu item pointing to a .md file that does not exist)
File does not use CRLF, but uses plain LF (hint: use cat -ve <filename> | grep $'\r' | wc -l and expect 0 as a result)
Has passed bart check
Has been manually tested by running in Spin/Bartholomew (hint: use PREVIEW_MODE=1 and run npm run styles to update styling)
Headings are using Title Case
Code blocks have the programming language set to properly highlight syntax and the proper copy directive
Have tested with npm run test and resolved all errors
Relates to an existing (potentially outdated) blog article? If so please add URL in blog to point to this content.

Signed-off-by: Thorsten Hans <[email protected]>

itowlson · 2025-01-09T19:05:54Z

content/spin/v3/command-trigger.md

+
+You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin.
+
+### Common Triggers


I am not sure what distinguishes a "common" trigger from a "community" one.

I thought separation would make sense. Although mqtt is mostly written by fermyon ppl, its not under the fermyon org.

If we don't care, we could roll with just a single (simple) list of all triggers

Maybe we just need to rephrase "common" to align more with "Fermyon"? It currently sounds like it contrasts with "rare" which is clearly not your intent!

itowlson · 2025-01-09T19:07:39Z

content/spin/v3/command-trigger.md

+
+You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin.
+
+### Common Triggers


I am wary of repeating this list on every trigger page. Could we maybe instead have a "See all Spin triggers" link to a top level page? Or nerd snip Karthik into giving us some kind of 'include from file' feature?

content/spin/v3/command-trigger.md

itowlson · 2025-01-09T19:11:13Z

content/spin/v3/command-trigger.md

+
+### Building and Running the Application
+
+We can immediately run this pre-written (template) application and observe the time-driven execution:


time-driven? Possible copypasta from cron?

itowlson · 2025-01-09T19:12:57Z

content/spin/v3/command-trigger.md

+<iframe width="560" height="315" src="https://www.youtube.com/embed/l2nh_xpjCiM?si=fBPaiqoIkJPQ95W_" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+If you would like to learn more about using the Spin Command Trigger, please check out the [Spin Command Trigger GitHub repository](https://github.com/fermyon/spin-trigger-command/).
+


Do we want to include a troubleshooting/gotchas section to cover how this doesn't play nice with multi-trigger applications?

For the command trigger that is definitely super important and useful. Will add a corresponding paragraph

itowlson · 2025-01-09T19:47:26Z

content/spin/v3/cron-trigger.md

+With the plugin and template installed, we create a new application:
+
+```bash
+spin new -t cron-rust hello_cron --accept-defaults


I'm not sure about --accept-defaults here - people presumably care about the actual execution schedule, so showing they get a chance to enter it might be good.

itowlson · 2025-01-09T19:48:59Z

content/spin/v3/command-trigger.md

+
+### Building and Running the Application
+
+We can immediately run this pre-written (template) application and observe the time-driven execution:


I am uncomfortable with "pre-written." "Template" or "starter" or "generated", but it's not really "pre-written".

itowlson · 2025-01-09T19:50:13Z

content/spin/v3/cron-trigger.md

+cd hello_cron
+spin build --up
+
+Building component hello-cron with `cargo build --target wasm32-wasi --release`


We should bump this to wasm32-wasip1 at some point (not a blocker here though)

definitely, however all our templates are still using wasm32-wasi

s/all/some\ of

content/spin/v3/triggers.md

itowlson · 2025-01-09T19:55:27Z

templates/spin_sidebar_v3.hbs

@@ -111,6 +111,26 @@
                                        {{/if}} href="{{site.info.base_url}}/spin/v3/redis-trigger">The Redis
                                        Trigger</a>
                        </li>
+                        <li><a {{#if (active_project request.spin-full-url "/spin/v3/command-trigger" )}} class="active"
+                                        {{/if}} href="{{site.info.base_url}}/spin/v3/command-trigger">The Command


What do you reckon is a good way to order the TOC here? The current scheme seems to be:

built ins, in order of importance

Fermyon-authored, in alphabetical? order

non-Fermyon-authored, unordered

This kind of requires users to know the provenance of their trigger in order to find it, which feels awkward.

On the other hand, strict alphabetical would make HTTP disappear into the middle of the list, which doesn't feel like it well serves the most common user needs.

Maybe we can simple add "Available triggers" to the sidebar, and link to that page from each trigger instead of listing all there... feels smarter

Yeah I like that, it that would also give us a nice landing page for inbound links (and a place to explain the different statuses of the different triggers)

Co-authored-by: itowlson <[email protected]> Signed-off-by: Thorsten Hans <[email protected]>

ogghead · 2025-01-10T01:55:50Z

content/spin/v3/community-kinesis-trigger.md

+
+> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `kinesis` because non-HTTP triggers are not supported in Fermyon Cloud.
+
+Let's look at how the [experimental Kinesis trigger for Spin](https://github.com/ogghead/spin-trigger-kinesis) allows you to deploy an application that runs based on real time data records streamed through AWS Kinesis. (Provisioning and configuring AWS Kinesis is out of scope for this article). The Kinesis trigger leverages AWS credentials from the standard AWS configuration environment variables and maps a AWS Kinesis stream to a specific component. For example:


We could clarify this by saying something like "parses data records streamed through AWS Kinesis with customizable processing delay" -- but I wonder if it gets into the weeds a bit too much.

ogghead · 2025-01-10T15:35:23Z

content/spin/v3/community-kinesis-trigger.md

+  ... DATA: { "value" : "bar" }
+```
+
+As we can see from the above output, our application is now running and executing the function for each data record sent through your individual AWS Kinesis instance.


Good callout @itowlson, agreed it might be worth rewording to clarify that function execution is per batch of records

ogghead · 2025-01-10T15:51:16Z

content/spin/v3/community-kinesis-trigger.md

+
+> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `kinesis` because non-HTTP triggers are not supported in Fermyon Cloud.
+
+Let's look at how the [experimental Kinesis trigger for Spin](https://github.com/ogghead/spin-trigger-kinesis) allows you to deploy an application that runs based on real time data records streamed through AWS Kinesis. (Provisioning and configuring AWS Kinesis is out of scope for this article). The Kinesis trigger leverages AWS credentials from the standard AWS configuration environment variables and maps a AWS Kinesis stream to a specific component. For example:


Knowing that an existing Kinesis stream and IAM credentials with permissions to read from it are prerequisites has benefit to readers if they are unfamiliar with AWS/are not ready to set those up. But it does also get into the weeds a bit.

Perhaps this information could live in a "prerequisites" subsection under "Installing the AWS Kinesis Trigger" before the sections on plugin installation/Spin configuration? Flexible on approach overall!

Unrelated, but it is potentially worth linking this AWS doc on credentials on "leverages AWS credentials from the standard AWS configuration environment variables" to help folks familiarize themselves with AWS credentials options.

kate-goldenring · 2025-01-10T22:58:26Z

content/spin/v3/triggers.md

-```bash
-spin plugins install --url https://github.com/fermyon/spin-trigger-cron/releases/download/canary/trigger-cron.json
-```
+### Common Triggers


To me, i see the categorization slightly differently, partially because i feel "common" is a little vague.

Triggers built into the spin CLI (http and redis)

Triggers maintained by Spin (command, cron, sqs, mqtt)

Community triggers (kinesis)

I bubbled MQTT into spin because it is a part of spinkube but i see how that could be seen as a community trigger too.

chore: rework Spin trigger docs

1d48460

Signed-off-by: Thorsten Hans <[email protected]>

ThorstenHans added the doNotMergeYet label Jan 9, 2025

ThorstenHans marked this pull request as draft January 9, 2025 16:24

itowlson requested changes Jan 9, 2025

View reviewed changes

ThorstenHans and others added 3 commits January 9, 2025 22:06

Update content/spin/v3/command-trigger.md

88967be

Co-authored-by: itowlson <[email protected]> Signed-off-by: Thorsten Hans <[email protected]>

Update content/spin/v3/community-kinesis-trigger.md

887f8f0

Co-authored-by: itowlson <[email protected]> Signed-off-by: Thorsten Hans <[email protected]>

Update content/spin/v3/triggers.md

453e9a3

Co-authored-by: itowlson <[email protected]> Signed-off-by: Thorsten Hans <[email protected]>

ogghead suggested changes Jan 10, 2025

View reviewed changes

kate-goldenring reviewed Jan 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[spin]: Rework trigger docs #1450

[spin]: Rework trigger docs #1450

ThorstenHans commented Jan 9, 2025

itowlson Jan 9, 2025

ThorstenHans Jan 9, 2025

itowlson Jan 9, 2025

itowlson Jan 9, 2025

itowlson Jan 9, 2025

itowlson Jan 9, 2025

ThorstenHans Jan 9, 2025

itowlson Jan 9, 2025

itowlson Jan 9, 2025

itowlson Jan 9, 2025

ThorstenHans Jan 9, 2025

ThorstenHans Jan 9, 2025

itowlson Jan 9, 2025

ThorstenHans Jan 9, 2025

itowlson Jan 9, 2025

ogghead Jan 10, 2025

ogghead Jan 10, 2025

ogghead Jan 10, 2025

kate-goldenring Jan 10, 2025


		You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin.

		### Common Triggers


		### Building and Running the Application

		We can immediately run this pre-written (template) application and observe the time-driven execution:

		<iframe width="560" height="315" src="https://www.youtube.com/embed/l2nh_xpjCiM?si=fBPaiqoIkJPQ95W_" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

		If you would like to learn more about using the Spin Command Trigger, please check out the [Spin Command Trigger GitHub repository](https://github.com/fermyon/spin-trigger-command/).


		> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `kinesis` because non-HTTP triggers are not supported in Fermyon Cloud.

		Let's look at how the [experimental Kinesis trigger for Spin](https://github.com/ogghead/spin-trigger-kinesis) allows you to deploy an application that runs based on real time data records streamed through AWS Kinesis. (Provisioning and configuring AWS Kinesis is out of scope for this article). The Kinesis trigger leverages AWS credentials from the standard AWS configuration environment variables and maps a AWS Kinesis stream to a specific component. For example:

[spin]: Rework trigger docs #1450

Are you sure you want to change the base?

[spin]: Rework trigger docs #1450

Conversation

ThorstenHans commented Jan 9, 2025

Sub Tasks

Pre-Merge Content Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment